OpenEdge Getting Started:<br />Core Business Services The client-principal object

Each client-principal object is created and managed by a 4GL application and represents a single user’s login session, which enables the tracking of a client from logging on to logging out of a Progress session. A client-principal object can be shared for single sign-on purposes, between or among different 4GL-type processes. For example, the object can be shared between any of the OpenEdge application servers, or any of the servers’ agents. The object can be used to set the current user ID for the 4GL application and optionally all of its OpenEdge database connections.

A client-principal object holds the user ID and other relevant user account and application data. It is a transportable user login-session token that the application being accessed can validate, understand, and use in its authorization system to control the 4GL application or database connection access to resources. You can use the client-principal object to set the application user ID for the 4GL application itself and, globally, the database connection ID from the database connections, as well as individually set a separate database connection ID for each database.

Each client-principal object must be sealed by the 4GL user authentication procedure with a domain access code upon login to prove that authentication was successful. The domain access code must be identical to the access code used to register the domain in either the Progress session or OpenEdge database’s registry. The client-principal also includes the domain name as a reference to a domain in those registries.

The client-principal object came from a trusted authentication source.

The client-principal object has not been tampered with.

The client-principal object has not expired.

The client-principal has not been logged out.

If any of these requirements fails, the client-principal object is not honored and is considered unusable; the user ID represented by the client-principal object is not validated or set.

There are two ways for the client-principal object to assert the ID of the user:

SECURITY-POLICY: SET-CLIENT( ) method — Uses the user ID associated with the sealed client-principal to set the default ID for the Progress session and attempts to use the client-principal to set the user ID on all connected OpenEdge databases (that do not already have an ID explicitly set).

SET-DB-CLIENT function — Uses the ID represented by a sealed and validated client-principal object to set a user ID for the specified OpenEdge database.

The SET-CLIENT( ) method and the SET-DB-CLIENT function do not authenticate user IDs; they validate them. When you validate the client-principal object, you are taking an authenticated user ID and making it useful within OpenEdge. If you successfully validate the client-principal object, the user ID is set as an application user ID or a database connection ID. With the SET-DB-CLIENT function, the database connection ID is set; with the SET-CLIENT( ) method, the application user ID is set. With the SET-CLIENT( ) method, you can also set the application user ID for a database that does not have a database connection ID explicitly set.